Suggested Workflow
==================

Efficiency is crucial when you're coding. To have readable, manageable
and stable code you need to have a number of habits that enable you to
quickly spot and track bugs, share code with others and deliver a
**working** output. We give hereby a simple workflow that might give
you a first glimpse into how to organise your work. These habits can
help you avoid standard issues related to writing no maintanable code,
too cumbersome to debug or read.

How is your repository organised?
---------------------------------

Your repository in its initial state contains:

- Configuration files ``dune-project`` and ``dune`` that specifies how and in
  which order your source ``.ml`` files are going to be compiled for you to
  generate project executables.

- A list of source files in the different subfolders of ``Source``,
  these are the ``.ml`` files at the core of your work.

- A list of ``.mli`` files that are called interface files, they
  specify and possibly restrict the type of functions defined in the
  corresponding ``.ml`` files. You should always have a look at them
  and avoid modifying them unless instructed to do otherwise.

- A list of **tests** subfolders containing unit tests for the
  different functions in the parent folder.

How to work?
------------

As a first approach, coding activities are summed by

- *editing source files*
- *testing edited functions*
- *testing of context and buildability of project*
- *Saving buildable state*
- *building project*

Editing source files is what you're mostly accustomed to ; you write
down code you expect to follow defined specifications. This implies
you using your preferred IDE. For our purposes ``Emacs`` in
``tuareg-mode`` is easily set-up and avaiable for you, you can still
use anything else as long as you're efficient and comfortable with it.

To test small edited functions while you're writing your code, rather than
executing the whole test suite made available for you, you're advised to make
local unit tests in the ``ocaml top-level`` with `emacs` or `utop`. The test
suite as a whole is heavy to launch and would need a rather expert eye to
analyse what went through and what didn't. You're given details on how to use
``ocaml top-level`` environment for micro-testing at :doc:`Compiling and Testing
Your Code`. If you're out of ideas for what to test you can look into the test
files within the **tests** folders, you have there (input, output) couples for
tested functions.

Testing context and buildability of project **is** about executing the
whole testing suite. This makes it possible to test whether you didn't
destroy anything you've previously coded and interconnexion between
your different source files.

To save buildable state, do the usual procedure, the same one as in your programming 
sessions. **Never do it when your code is not buildable**. Your code must compile and 
execute your local testsuites with no crash or timeout.

.. admonition:: More Professional Workflows
   If you're proficient enough in ``git`` you can ask your tutors
   for more professional workflows. If not, you can still ask out
   of curiousity, you are advised to keep it simple though.